WebAPI: Document API using OpenAPI #21817
Conversation
Just to confirm, was this PR generated manually? It would be incredible to have the docs generated automatically, even if the docs weren't perfect. |
|
The YAML file was created manually. Supposedly there are openapi code scanners -> yaml, but I very much doubt they will work correctly with our custom C++ server. |
|
👍🏼 I definitely support this. My process has depended on reading the code to understand the API signatures. This should also help make finding differences among versions much easier. This obviously all depends on keeping the spec up-to-date; fortunately, I am able to automatically create one for the Python interface. |
This is simply a demo.
sledgehammer999
force-pushed
the
openapi_demo
branch
from
3e77ff1 to
0ef310d
Compare
|
You can now preview the OpenAPI spec in the browser: https://www.qbittorrent.org/openapi-demo/ |
This is simply a demo to foster input from the community.
The process of documenting the WebAPI leaves a lot to be desired. Both in terms of actually writing down the specs and rendering them in a visually pleasing way to the end user.
The OpenAPI spec was developed for this and seems to be industry standard.
A quick guide is here.
Since it is standardized there are loads of tools that help with exploring the API, writing clients, validating, rendering documentation etc.
I am interested mainly in a) providing an easy way for others to validate their clients and b) generating helpful documentation.
I have documented the APIs of the
transferandauthcontrollers as a demo. As you can see each controller can be documented in its own YAML and be referenced by the main YAML. This will help with incrementally implementing OpenAPI if we decide to go that route.If we decide to use OpenAPI, then for each controller that is documented we will require that each PR that affects its API to also make necessary changes to the OpenAPI yaml.
The generated docs can be hooked up to be served by the mainsite (CI integration should help here).
You can preview it here: https://www.qbittorrent.org/openapi-demo/